/*
 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */
package java.util.stream;

import java.util.Iterator;
import java.util.Spliterator;

/**
 *  流的基本界面，它们是支持顺序和并行聚合操作的元素序列。 以下示例说明了使用流类型Stream和IntStream的汇总操作 ，计算红色小部件的权重之和：
 *     int sum = widgets.stream()
 *                      .filter(w -> w.getColor() == RED)
 *                      .mapToInt(w -> w.getWeight())
 *                      .sum();
 *
 * @since 1.8
 * @see Stream
 * @see IntStream
 * @see LongStream
 * @see DoubleStream
 */
public interface BaseStream<T, S extends BaseStream<T, S>>
        extends AutoCloseable {
    /**
     * 返回此流的元素的迭代器
     * @return 该流的元素迭代器
     */
    Iterator<T> iterator();

    /**
     * 返回此流的元素的拼接器
     * @return 该流的元素拼接器
     */
    Spliterator<T> spliterator();

    /**
     * 返回此流是否要执行终端操作，将并行执行。
     * 在调用终端流操作方法后调用此方法可能会产生不可预测的结果。
     * @return true如果这个流如果被执行则并行执行
     */
    boolean isParallel();

    /**
     * 返回顺序的等效流。
     * 可能返回自己，因为流已经是顺序的，或者因为底层流状态被修改为顺序的。
     * @return 顺序流
     */
    S sequential();

    /**
     * 返回平行的等效流。
     * 可能会返回自己，因为流已经是并行的，或者因为底层流状态被修改为并行。
     * @return 并行流
     */
    S parallel();

    /**
     * 返回等效的流，
     * 即unordered 。 可能会返回自己，因为流已经无序，或者因为基础流状态被修改为无序。
     * @return 无序的流
     */
    S unordered();

    /**
     * 返回带有附加关闭处理程序的等效流。
     * 在流上调用close()方法时运行关闭处理程序，并按照添加的顺序执行。
     * 所有关闭的处理程序都运行，即使较早的关闭处理程序抛出异常。 如果任何关闭处理程序抛出异常，
     * 则抛出的第一个异常将被中继到close()的调用者， close()将异常添加到该异常中作为禁止异常（除非其中一个异常与第一个异常相同，否则为第一个异常）异常不能压制自己。）可能返回自己。
     * @param closeHandler 流关闭时执行的任务
     * @return 具有处理程序的流，如果流已关闭，则运行该流
     */
    S onClose(Runnable closeHandler);

    /**
     * 关闭此流，导致此流管道的所有关闭处理程序被调用。
     * @see AutoCloseable#close()
     */
    @Override
    void close();
}
